/**
 * @addtogroup brd_timer
 * brd_timer
 * @{
 */
/**
 * @file brd_timer.h
 * @brief 定时器板级层
 * @par 修改日志
 * <table>
 * <tr><th>Date <th>Version <th>Author <th>Description
 * <tr><td>2020-11-10 <td>1.0 <td>软件工程院 <td>创建初始版本
 * @par 示例
 * @code
 * UInt8 max_count;
   UInt32 tick;
   Brd_THandle handle;
   ...
   tick = Brd_TimerServerTick();
   max_count = Brd_TimerMaxCount();
   ...
   handle = Brd_TimerCreate();
   if (handle != NULL)
   {
      Brd_TimerSetEventReceiver(handle, xxx);
      Brd_TimerSetEvent(handle, yyy);
      Brd_TimerSetInterval(handle, 10);
      Brd_TimerStart(handle);
      ...
      // do something
      ...
      Brd_TimerStop(handle);
   }
   ...
   Brd_TimerCloseServer();
   ...
 * @endcode 
 * @copyright 杭州鸿泉物联网技术股份有限公司
 */

#ifndef _BRD_TIMER_H_
#define _BRD_TIMER_H_

#include <ofc_types.h>
#include <brd_common.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * 定时器定时事件的函数类型
 * @param handle: 事件的产生者
 * @return 无返回值
 */
typedef void (*Brd_TOnTimerEvent)(Brd_THandle handle);

/**
 * 获取定时服务器节拍计数
 * @note 节拍计数值只有在[Brd_Open](@ref Brd_Open)打开后才会累加
 * @return 返回节拍计数值, 单位为毫秒(ms)
 */
UInt32 Brd_TimerServerTick(void);

/**
 * 获取能够创建的定时器最大数量
 * @return 返回能够创建的定时器最大个数
 */
UInt8 Brd_TimerMaxCount(void);

/**
 * 创建定时器对象.
 * @note
 *   -# 定时器一旦创建,无法释放
 *   -# 当定时器个数超过[Brd_TimerMaxCount](@ref Brd_TimerMaxCount)时,创建失败
 * @return 创建的定时器对象, 该定时器不允许外部释放.如果创建失败返回NULL
 */
Brd_THandle Brd_TimerCreate(void);

/**
 * 获取事件接收者
 * @param handle: 句柄
 * @return 返回事件接收者
 */
void *Brd_TimerEventReceiver(Brd_THandle handle);

/**
 * 设置事件接收者
 * @param handle: 句柄
 * @param receiver: 事件接收者
 * @return 无返回值
 */
void Brd_TimerSetEventReceiver(Brd_THandle handle, void *receiver);

/**
 * 设置定时时间超时后触发的事件
 * @note 当事件产生时直接告知用户去处理, 在中断函数里面调用本函数, \n
 *       因此需要用户保持警惕, 切勿处理高延迟或不能在中断里面处理的操作
 * @param handle: 句柄
 * @param on_event: 事件方法
 * @return 无返回值
 */
void Brd_TimerSetEvent(Brd_THandle handle, Brd_TOnTimerEvent on_event);

/**
 * 获取定时器的定时间隔
 * @param handle: 句柄
 * @return 返回定时间隔, 单位为毫秒(ms)
 */
UInt32 Brd_TimerInterval(Brd_THandle handle);

/**
 * 设置定时间隔
 * @param handle: 句柄
 * @param ms: 定时间隔,单位ms
 * @return 无返回值
 */
void Brd_TimerSetInterval(Brd_THandle handle, UInt32 ms);

/**
 * 启动定时器
 * @note 启动后首次OnTimer事件会发生在定时间隔减一到定时间隔之间; \n
 *       如果定时间隔设置为1,则会在定时器使能时刻到1ms时触发OnTimer
 * @param handle: 句柄
 * @return 无返回值
 */
void Brd_TimerStart(Brd_THandle handle);

/**
 * 停止定时器
 * @param handle: 句柄
 * @return 无返回值
 */
void Brd_TimerStop(Brd_THandle handle);

#ifdef __cplusplus
}  ///< extern "C"
#endif

#endif // _BRD_TIMER_H_
/**
 * @} 
 */
